Skip to main content

Browse Collections & Fetch a Clip

This guide covers how to discover music Collections, read the clip IDs they contain, fetch a clip's signed URL, and optionally retrieve a full track for custom clip creation.

Prerequisites​

Overview of the flow​

  1. List or browse Collections to discover what music is available.
  2. Read clip IDs from the Collection response.
  3. Fetch one or more clips to get their signed URLs.
  4. Optionally fetch a full track if you need the source audio for custom clipping.

Step 1: List Collections​

Send a GET /v2/collections request to retrieve all Collections available to your account. Collections are curated thematic groupings of clips maintained by Feed's curation team. See the Fetch Collections reference for the full contract.

To retrieve a specific Collection by ID, use GET /v2/collections/{id}. See the Fetch Collection reference.

Step 2: Browse a Collection's clips​

Each Collection response includes the clip IDs and track IDs it contains along with clip metadata (title, artist, artwork URL, etc). These IDs are the keys to everything else in the API.

To retrieve only the clip list for a given Collection without the full Collection metadata, use GET /v2/collections/{id}/clips. See the Fetch Collection Clips reference.

Step 3: Fetch one or more clips​

Use the clip IDs from the Collection to fetch signed audio URLs. There are two endpoints:

  • Fetch multiple clips at once: GET /v2/clips — pass one or more clipIds to receive signed URLs and metadata for each. See the Fetch Clips reference.
  • Fetch a single clip: GET /v2/clips/{id} — use this when you need only one clip. See the Fetch Clip reference.

The signed URL returned by these endpoints is valid for 24 hours. Download and cache the audio file within that window; do not link directly from the signed URL during playback.

Handling partial failures​

When fetching multiple clips in a single request, individual clips may fail while others succeed. The response uses a per-item success envelope so that a single unavailable clip does not fail the whole batch. Always inspect each item's success field before using it. See The Response & Error Model for details on the envelope format and failure codes.

Step 4 (optional): Fetch a full track​

If you want to offer custom clip creation in your app, you need the full-length source audio. Use GET /v2/tracks/{id} with the trackId from the Collection response. See the Fetch Track reference.

The track response also includes a curatedClip object when Feed has designated a best section for the track. This is useful for pre-populating a custom clipping UI. See Create a Custom Clip for the complete flow.

v1 vs v2

In v1, Collections and clips were retrieved using POST /collections and POST /music-fetch respectively. Both used POST with a JSON body. In v2, these are GET requests with query parameters (/v2/collections, /v2/clips), following standard REST conventions.

Next steps​